# 固件架构与源码

```{admonition} 本文引用的文件
:class: note

- `firmware/port/README.md`
- `esp32s3/firmware/README.md`
- `firmware/port/mpconfigport.h`
- `firmware/port/Makefile`
- `esp32s3/firmware/CMakeLists.txt`
- `esp32s3/firmware/esp32_common.cmake`
- `esp32s3/firmware/makeimg.py`
- `esp32s3/firmware/main/CMakeLists.txt`
- `esp32s3/firmware/boards/mpython_v3/mpconfigboard.cmake`
- `esp32s3/firmware/boards/labplus_Ledong_v2/mpconfigboard.cmake`
- `esp32s3/firmware/boards/manifest.py`
- `firmware/port/builtins/modmachine.c`
- `firmware/port/builtins/modmusic.c`
- `firmware/port/builtins/modnetwork.c`
- `firmware/port/builtins/modradio.c`
- `firmware/port/builtins/modframebuf.c`
- `firmware/port/builtins/modmotion.c`
- `firmware/port/builtins/modcodec.c`
- `firmware/port/builtins/modxunfeiAI.c`
- `firmware/port/modules/ssd1106.py`
- `firmware/port/modules/neopixel.py`
- `firmware/port/modules/mpython_ble/application/codexpad.py`
- `firmware/port/file_system/siot.py`
- `firmware/port/file_system/xunfei.py`
- `firmware/port/file_system/yeelight.py`
- `firmware/port/file_system/smartcamera.py`
- `esp32s3/firmware/modules/radio.py`
- `esp32s3/firmware/modules/ai_cloud.py`
- `esp32s3/firmware/modules/xunfei.py`
```

## 产品概述
mPython掌控板是基于ESP32双核芯片的MicroPython微控制器平台，面向K12创客教育场景。固件以MicroPython为核心，在FreeRTOS上运行，提供REPL、文件系统、GPIO/ADC/PWM/I2C/SPI等外设能力，以及WiFi/BLE网络、音频、传感器、显示等扩展能力。项目同时维护了两条产品线：
- ESP32版（firmware/port）：成熟稳定，内置大量C级模块与Python扩展库，适合教学与快速原型。
- ESP32-S3版（esp32s3/firmware）：基于ESP-IDF v5.x + CMake构建，新增LVGL/AI视觉、GPS、心率等能力，支持多板型（mpython_v3、labplus_Ledong_v2等）。

核心价值在于“C层高性能+Python层易用性”的分层设计，既满足底层驱动性能需求，又通过Python模块降低开发门槛；构建流程清晰、板型配置解耦，便于二次开发与定制。

**章节来源**
- `firmware/port/README.md:1-20`
- `esp32s3/firmware/README.md:1-20`

## 核心业务流程
- 启动与初始化
  - 引导程序加载分区表与应用镜像，FreeRTOS任务调度MicroPython VM。
  - 端口层初始化串口REPL、内存管理、VFS、网络栈、蓝牙等。
- 用户代码执行
  - Python脚本从冻结模块或LittleFS文件系统加载执行。
  - 调用C级builtins（如machine/music/network）或直接使用Python模块（如neopixel/gui）。
- 硬件交互
  - C驱动访问外设（I2C/SPI/ADC/PWM/TIMERS），暴露为Python接口。
  - 传感器/音频/显示等通过drivers与modules组合实现。
- 构建与烧录
  - ESP32版使用Makefile+ESP-IDF v3/v4；ESP32-S3版使用idf.py+CMake。
  - 生成bootloader/partitions/app/VFS/语音模型等，合并为最终固件镜像。

```text
sequenceDiagram
participant Boot as "引导程序"
participant IDF as "ESP-IDF/FreeRTOS"
participant MP as "MicroPython VM"
participant Py as "用户Python脚本"
participant Mod as "C级模块/Python模块"
participant HW as "硬件外设"
Boot->>IDF : 加载分区表与应用
IDF->>MP : 创建并启动VM任务
MP->>Py : 执行boot.py/main.py
Py->>Mod : 调用machine/music/network等
Mod->>HW : 读写寄存器/中断/DMA
HW-->>Mod : 数据/事件
Mod-->>Py : 返回结果/回调
Py-->>MP : 继续执行/退出
```

**图表来源**
- `esp32s3/firmware/esp32_common.cmake:126-180`
- `esp32s3/firmware/makeimg.py:179-200`

**章节来源**
- `esp32s3/firmware/esp32_common.cmake:126-180`
- `esp32s3/firmware/makeimg.py:179-200`

## 功能模块清单
- C级编译模块（builtins）
  - machine：GPIO/ADC/PWM/I2C/SPI/TouchPad/Timer等基础外设控制。
  - music：兼容micro:bit的音乐播放与节拍控制。
  - network/WiFi：WLAN连接与网络协议栈。
  - radio：无线广播（ESP32版）。
  - framebuf：帧缓冲绘制。
  - motion：六轴传感器（加速度/陀螺仪/磁力计）。
  - codec：音频编解码与录音/播放（ESP32版）。
  - xunfeiAI：讯飞语音听写与TTS（ESP32版）。
- Python级模块（modules）
  - 设备驱动与工具：ssd1106(OLED)、neopixel(WS2812)、gui、logging、weather等。
  - BLE高级库：mpython_ble（advertising/services/gatts等）。
  - 网络与物联网：urequests、umqtt、tinywebio、siot等。
- 硬件驱动（drivers）
  - codec、mpu6050、rfid、rgbLED5x5等底层C驱动。
- 文件系统扩展（file_system）
  - siot(SIoT物联网)、yeelight(智能灯)、xunfei(讯飞AI)、smartcamera(AI摄像头)等应用级库。

```text
graph TB
subgraph "C级模块(builtins)"
M["modmachine"]
U["modmusic"]
N["modnetwork"]
R["modradio"]
F["modframebuf"]
O["modmotion"]
A["modcodec"]
X["modxunfeiAI"]
end
subgraph "Python模块(modules)"
S["ssd1106"]
P["neopixel"]
G["gui"]
B["mpython_ble"]
Q["urequests/umqtt"]
end
subgraph "驱动(drivers)"
D1["codec"]
D2["mpu6050"]
D3["rfid"]
D4["rgbLED5x5"]
end
subgraph "文件系统(file_system)"
FS1["siot"]
FS2["yeelight"]
FS3["xunfei"]
FS4["smartcamera"]
end
M --> D1
M --> D2
M --> D3
M --> D4
U --> M
N --> M
R --> M
F --> M
O --> M
A --> M
X --> N
S --> M
P --> M
G --> F
B --> N
Q --> N
FS1 --> N
FS2 --> N
FS3 --> N
FS4 --> N
```

**图表来源**
- `firmware/port/builtins/modmachine.c`
- `firmware/port/builtins/modmusic.c`
- `firmware/port/builtins/modnetwork.c`
- `firmware/port/builtins/modradio.c`
- `firmware/port/builtins/modframebuf.c`
- `firmware/port/builtins/modmotion.c`
- `firmware/port/builtins/modcodec.c`
- `firmware/port/builtins/modxunfeiAI.c`
- `firmware/port/modules/ssd1106.py`
- `firmware/port/modules/neopixel.py`
- `firmware/port/modules/mpython_ble/application/codexpad.py`
- `firmware/port/file_system/siot.py`
- `firmware/port/file_system/xunfei.py`
- `firmware/port/file_system/yeelight.py`
- `firmware/port/file_system/smartcamera.py`

**章节来源**
- `firmware/port/builtins/modmachine.c`
- `firmware/port/builtins/modmusic.c`
- `firmware/port/builtins/modnetwork.c`
- `firmware/port/builtins/modradio.c`
- `firmware/port/builtins/modframebuf.c`
- `firmware/port/builtins/modmotion.c`
- `firmware/port/builtins/modcodec.c`
- `firmware/port/builtins/modxunfeiAI.c`
- `firmware/port/modules/ssd1106.py`
- `firmware/port/modules/neopixel.py`
- `firmware/port/modules/mpython_ble/application/codexpad.py`
- `firmware/port/file_system/siot.py`
- `firmware/port/file_system/xunfei.py`
- `firmware/port/file_system/yeelight.py`
- `firmware/port/file_system/smartcamera.py`

## 数据与状态
- 构建配置与开关
  - mpconfigport.h集中定义MicroPython特性开关（线程、VFS、SSL、WebREPL、FrameBuffer等）、内置模块注册、根指针与平台标识。
  - 板级cmake（mpython_v3/labplus_Ledong_v2）指定目标芯片、SDKCONFIG默认集、源文件列表与冻结清单。
- 模块依赖关系
  - builtins通过mpconfigport.h注册为内置模块名（machine/network/music/audio/radio等），被Python层直接import。
  - modules与file_system作为扩展库，按需要冻结到固件或通过文件系统加载。
- 运行时状态
  - FreeRTOS任务调度MicroPython VM；事件钩子处理挂起任务与异步事件。
  - VFS将LittleFS挂载为内部文件系统，存储用户脚本与资源。
  - NVS用于持久化配置（如传感器偏移、网络凭据等）。

```text
flowchart TD
Start(["构建入口"]) --> Cfg["读取mpconfigport.h<br/>与板级cmake"]
Cfg --> Modules{"启用哪些模块?"}
Modules --> |C级| Builtin["注册builtins<br/>machine/network/music..."]
Modules --> |Python| Freeze["冻结modules/file_system"]
Builtin --> Build["编译链接"]
Freeze --> Build
Build --> Pack["makeimg.py打包<br/>bootloader/partitions/app/VFS/语音模型"]
Pack --> Flash["烧录到Flash"]
Flash --> Run["FreeRTOS启动MicroPython"]
Run --> App["执行用户脚本"]
App --> State["运行时状态: VFS/NVS/网络/外设"]
```

**图表来源**
- `firmware/port/mpconfigport.h:14-61`
- `firmware/port/mpconfigport.h:180-218`
- `esp32s3/firmware/boards/mpython_v3/mpconfigboard.cmake:1-44`
- `esp32s3/firmware/boards/labplus_Ledong_v2/mpconfigboard.cmake:1-50`
- `esp32s3/firmware/makeimg.py:179-200`

**章节来源**
- `firmware/port/mpconfigport.h:14-61`
- `firmware/port/mpconfigport.h:180-218`
- `esp32s3/firmware/boards/mpython_v3/mpconfigboard.cmake:1-44`
- `esp32s3/firmware/boards/labplus_Ledong_v2/mpconfigboard.cmake:1-50`
- `esp32s3/firmware/makeimg.py:179-200`

## 关键约束与边界
- 构建系统差异
  - ESP32版：Makefile + ESP-IDF v3/v4，需设置ESPIDF路径与工具链，支持BOARD变量选择板型。
  - ESP32-S3版：idf.py + CMake，顶层CMakeLists.txt包含板级配置，支持variant与lockfiles校验。
- 板型与配置边界
  - 每个板型有独立mpconfigboard.cmake与sdkconfig集合，避免交叉污染。
  - 冻结清单(manifest.py)决定Python模块是否内嵌，影响固件体积与启动时间。
- 模块可用性边界
  - ESP32版：audio/radio/xunfeiAI为C级内置；ESP32-S3版：radio迁移至Python模块，新增ai_cloud/xunfei等。
  - 部分引脚/外设受限（如P4光线、P10声音），通用IO需避开专用功能。
- 运行时约束
  - 堆栈与内存：MicroPython任务栈与Python堆大小有限，需关注大对象分配。
  - 网络与BLE：需正确配置天线与RF参数，不同板型可能需额外初始化。
- 集成与扩展边界
  - drivers与modules分层清晰，新增驱动应优先放入drivers，Python封装放在modules。
  - file_system中的扩展库属于应用层，不纳入核心构建，按需部署。

**章节来源**
- `firmware/port/Makefile:1-200`
- `esp32s3/firmware/CMakeLists.txt:1-107`
- `esp32s3/firmware/main/CMakeLists.txt:1-14`
- `esp32s3/firmware/boards/manifest.py:1-16`
- `esp32s3/firmware/modules/radio.py`
- `esp32s3/firmware/modules/ai_cloud.py`
- `esp32s3/firmware/modules/xunfei.py`